<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
    <title>The Blue Hole Framework (BHF)</title>
    <base href="http://bhs.googlecode.com/svn/trunk/"><!--[if IE]></base><![endif]-->
</head>
<body>
<h1>The Blue Hole Framework (BHF)</h1>
<p>The Blue Hole Framework is an evolution of the <a href="https://swf.dev.java.net/">Simple Web Framework</a> to
    incorporate recent advances in JavaScript application programming, specifically AJAX techniques, and what we have
    learned using SWF over the last two years. As is the case with SWF, the Blue Hole Framework supports server side
    events, server side rendering, and In Place Updating (IPU). While SWF hid JavaScript from the application
    programmer, Blue Hole embraces and exposes JavaScript as a first class technology for portions of application
    development.</p>
<p>The BHF includes four layers with strict dependency control such that a lower layer is not dependent on a higher
    layer. For example, you can use the <a href="docs/javadocs/org/bhf/json/package-summary.html">"Worlds Fastest
    JSON Library"</a> without any the overhead of, or commitment to, the Service or Component libraries.</p>
<p>The BHF project is hosted at <a href="http://code.google.com/p/bhf">Google Code</a>;
    the most recent release may be found at <a href="http://www.blueholesoftware.com/bhf/">Blue Hole Software</a>.</p>

<h2>API References</h2>
<ul>
    <li><a href="docs/javadocs/index.html">Java Docs</a></li>
    <li><a href="docs/jsdocs/index.html">JavaScript</a></li>
    <li><a href="docs/tag/index.html">JSP Taglibs</a></li>
</ul>

<h2>JSON</h2>
<p>The BHF provides the <a href="docs/javadocs/org/bhf/json/package-summary.html">"Worlds Fastest JSON Library"</a>
    for marshalling and unmarshalling Java objects in JSON. BHF JSON is different than other JSON libraries in that it
    1) generates code at runtime to parse and write JSON, instead of using reflection and 2) works with native
    Java objects rather than providing classes like JSONOBject, JSONArray, etc. or out-of-band constructs like
    class maps or class hints.
</p>

<h3>YUI Dependency</h3>
<p>After much agonizing, we decided to leverage the Yahoo! YUI JavaScript libraries rather than roll our own or
depend on another one of the popular projects like Prototype. While YUI files are not small, you can leverage
Yahoo!'s edge servers to provide the JavaScript files much faster than you can probably achieve with your own servers
(if your security situation allows the use of an exteral server). We realize than many will not want a dependency upon
YUI, so we have tried to make it easy for you to use any AJAX/JSON library to access BHF services and components,
if you so chose. More information can be found at
<a href="http://yuiblog.com/blog/2007/02/22/free-yui-hosting">http://yuiblog.com/blog/2007/02/22/free-yui-hosting</a> and
<a href="http://yuiblog.com/blog/2006/10/16/pageweight-yui0114/">http://yuiblog.com/blog/2006/10/16/pageweight-yui0114/</a>.
</p>
<h3>What you need:</h3>
<ul>
    <li><a href="download/@bhf-json.jar@">bhf-json.jar</a></li>
    <li><a href="download/@javassist.jar@">javassist.jar</a></li>
</ul>
<h3>What you need to know:</h3>
<ul>
    <li><a href="docs/javadocs/org/bhf/json/package-summary.html">BHF JSON API</a></li>
</ul>

<h2>Services</h2>
<p>Need an easy way to write <a href="docs/writing-services.html">high performance JSON services?</a>. While
    any client library (JavaScript or otherwise) can be used to invoke BHF JSON services, the BHF also provides
    <a href="docs/calling-services.html">JavaScript support tailored specifically for BHF</a>.
</p>
<h3>What you need:</h3>
<ul>
    <li><a href="download/@bhf.jar@">bhf.jar</a></li>
    <li><a href="download/@bhf-jsp.jar@">bhf-jsp.jar (optional)</a></li>
    <li><a href="download/@javassist.jar@">javassist.jar</a></li>
    <li><a href="download/@bhs.js@">bhs.js (optional)</a></li>
</ul>
<h3>What you need to know:</h3>
<ul>
    <li>How to write and run a Java web application</li>
    <li><a href="docs/javadocs/org/bhf/json/package-summary.html">BHF JSON API</a></li>
    <li><a href="docs/javadocs/org/bhf/service/package-summary.html">BHF Services API</a></li>
    <li><a href="docs/jsdocs/index.htm">bhf-services.js</a></li>
    <li><a href="docs/writing-services.html">Writing Services</a></li>
    <li><a href="docs/calling-services.html">Calling Services</a></li>
</ul>


<h2>Components</h2>
<p>
    Components are Services with state and events: both client side. When you invoke a Service method, the argument
    to the method is marshalled and sent to the server. When you invoke a method on a Component, the Component's
    state and the argument are both packed up and sent to the server. A Service method returns a simple result, while
    a Component method returns not only the method result, but possibly updated Component state and events to fire.
    State makes Components more powerful constructs than Services, but also raise challenges, in the context of
    asynchronous method invocations, similar to the pains of multi-threaded environments.
</p>
<h3>What you need:</h3>
<ul>
    <li><a href="download/@bhf.jar@">bhf.jar</a></li>
    <li><a href="download/@bhf-jsp.jar@">bhf-jsp.jar (optional)</a></li>
    <li><a href="download/@javassist.jar@">javassist.jar</a></li>
    <li><a href="download/@bhs.js@">bhs.js (optional)</a></li>
</ul>
<h3>What you need to know:</h3>
<ul>
    <li>How to write and run a Java web application</li>
    <li><a href="docs/javadocs/org/bhf/json/package-summary.html">BHF JSON API</a></li>
    <li><a href="docs/javadocs/org/bhf/service/package-summary.html">BHF Services API</a></li>
    <li><a href="docs/javadocs/org/bhf/component/package-summary.html">BHF Component API</a></li>
    <li><a href="docs/jsdocs/index.htm">bhf-component.js</a></li>
    <li><a href="docs/writing-services.html">Writing Services</a></li>
    <li><a href="docs/calling-services.html">Calling Services</a></li>
    <li><a href="docs/writing-components.html">Writing Components</a></li>
    <li><a href="docs/calling-components.html">Calling Components</a></li>
    <li><a href="docs/safe-ajax/index.html">Safe AJAX: Taming the Asynchronous State Threat</a></li>
</ul>

<h2>Widgets</h2>
<p>
    Widgets are Components with a visual presentation and messages.
</p>
<h3>What you need:</h3>
<ul>
    <li><a href="download/@bhf.jar@">bhf.jar</a></li>
    <li><a href="download/@bhf-jsp.jar@">bhf-jsp.jar (optional)</a></li>
    <li><a href="download/@javassist.jar@">javassist.jar</a></li>
    <li><a href="download/@bhs.js@">bhs.js (optional)</a></li>
</ul>
<h3>What you need to know:</h3>
<ul>
    <li>How to write and run a Java web application</li>
    <li><a href="docs/javadocs/org/bhf/json/package-summary.html">BHF JSON API</a></li>
    <li><a href="docs/javadocs/org/bhf/service/package-summary.html">BHF Services API</a></li>
    <li><a href="docs/javadocs/org/bhf/component/package-summary.html">BHF Component API</a></li>
    <li><a href="docs/javadocs/org/bhf/widget/package-summary.html">BHF Widget API</a></li>
    <li><a href="docs/jsdocs/index.htm">bhf-component.js</a></li>
    <li><a href="docs/writing-services.html">Writing Services</a></li>
    <li><a href="docs/calling-services.html">Calling Services</a></li>
    <li><a href="docs/writing-components.html">Writing Components</a></li>
    <li><a href="docs/calling-components.html">Calling Components</a></li>
    <li><a href="docs/writing-widgets.html">Writing Widgets</a></li>
    <li><a href="docs/calling-widgets.html">Calling Widgets</a></li>
    <li><a href="docs/safe-ajax/index.html">Safe AJAX: Taming the Asynchronous State Threat</a></li>
</ul>
<h2>Validation</h2>
<p>
    The BHF provides an annotation based validation subsystem, if you choose to use it. It is included in bhf-widgets
    JAR and applied whenever the <code>Validate</code> annotation is attached to a widget method. You can also use
    your own validation mechanism or ad hoc validation within any widget method. (Validation is only understood
    client side by the widget dispatch mechanism. Widgets are the first level of the BHF that has the concept of
    visual representation and, thus, of the human readable messages produces by validation.)
</p><p>
    The BHF validator does not perform syntactic validation to guarantee a JSON object will populate a Java object.
    For example, if the Java object has an int property, you must ensure that the client passes an integer object
    in the JSON stream. Usually, you will want to pass form data as strings, validate, and then perform any type
    conversion you might desire, thus side stepping the syntax issue and shifting the burden server side.
</p><p>
    <a href="docs/javadocs/org/bhf/validation/package-summary.html">BHF Services API</a>
</p>
<h2>Cross Site Request Forgery Attacks (CSRF)</h2>
<p>
    <a href="docs/csrf.html">CSRF Token Support</a>
</p>
</body>
</html>